`egui`: an easy-to-use GUI in pure Rust!
Try the live web demo: . Read more about egui at .
`egui` is in heavy development, with each new version having breaking changes.
You need to have rust 1.61.0 or later to use `egui`.
To quickly get started with egui, you can take a look at [`eframe_template`](https://github.com/emilk/eframe_template)
which uses [`eframe`](https://docs.rs/eframe).
To create a GUI using egui you first need a [`Context`] (by convention referred to by `ctx`).
Then you add a [`Window`] or a [`SidePanel`] to get a [`Ui`], which is what you'll be using to add all the buttons and labels that you need.
# Using egui
To see what is possible to build with egui you can check out the online demo at .
If you like the "learning by doing" approach, clone and get started using egui right away.
### A simple example
Here is a simple counter that can be incremented and decremented using two buttons:
```
fn ui_counter(ui: &mut egui::Ui, counter: &mut i32) {
// Put the buttons and label on the same row:
ui.horizontal(|ui| {
if ui.button("-").clicked() {
*counter -= 1;
}
ui.label(counter.to_string());
if ui.button("+").clicked() {
*counter += 1;
}
});
}
```
In some GUI frameworks this would require defining multiple types and functions with callbacks or message handlers,
but thanks to `egui` being immediate mode everything is one self-contained function!
### Getting a [`Ui`]
Use one of [`SidePanel`], [`TopBottomPanel`], [`CentralPanel`], [`Window`] or [`Area`] to
get access to an [`Ui`] where you can put widgets. For example:
```
# egui::__run_test_ctx(|ctx| {
egui::CentralPanel::default().show(&ctx, |ui| {
ui.add(egui::Label::new("Hello World!"));
ui.label("A shorter and more convenient way to add a label.");
if ui.button("Click me").clicked() {
// take some action here
}
});
# });
```
### Quick start
```
# egui::__run_test_ui(|ui| {
# let mut my_string = String::new();
# let mut my_boolean = true;
# let mut my_f32 = 42.0;
ui.label("This is a label");
ui.hyperlink("https://github.com/emilk/egui");
ui.text_edit_singleline(&mut my_string);
if ui.button("Click me").clicked() { }
ui.add(egui::Slider::new(&mut my_f32, 0.0..=100.0));
ui.add(egui::DragValue::new(&mut my_f32));
ui.checkbox(&mut my_boolean, "Checkbox");
#[derive(PartialEq)]
enum Enum { First, Second, Third }
# let mut my_enum = Enum::First;
ui.horizontal(|ui| {
ui.radio_value(&mut my_enum, Enum::First, "First");
ui.radio_value(&mut my_enum, Enum::Second, "Second");
ui.radio_value(&mut my_enum, Enum::Third, "Third");
});
ui.separator();
# let my_image = egui::TextureId::default();
ui.image(my_image, [640.0, 480.0]);
ui.collapsing("Click to see what is hidden!", |ui| {
ui.label("Not much, as it turns out");
});
# });
```
## Conventions
Conventions unless otherwise specified:
* angles are in radians
* `Vec2::X` is right and `Vec2::Y` is down.
* `Pos2::ZERO` is left top.
* Positions and sizes are measured in _points_. Each point may consist of many physical pixels.
# Integrating with egui
Most likely you are using an existing `egui` backend/integration such as [`eframe`](https://docs.rs/eframe), [`bevy_egui`](https://docs.rs/bevy_egui),
or [`egui-miniquad`](https://github.com/not-fl3/egui-miniquad),
but if you want to integrate `egui` into a new game engine, this is the section for you.
To write your own integration for egui you need to do this:
``` no_run
# fn handle_platform_output(_: egui::PlatformOutput) {}
# fn gather_input() -> egui::RawInput { egui::RawInput::default() }
# fn paint(textures_detla: egui::TexturesDelta, _: Vec) {}
let mut ctx = egui::Context::default();
// Game loop:
loop {
let raw_input: egui::RawInput = gather_input();
let full_output = ctx.run(raw_input, |ctx| {
egui::CentralPanel::default().show(&ctx, |ui| {
ui.label("Hello world!");
if ui.button("Click me").clicked() {
// take some action here
}
});
});
handle_platform_output(full_output.platform_output);
let clipped_primitives = ctx.tessellate(full_output.shapes); // create triangles to paint
paint(full_output.textures_delta, clipped_primitives);
}
```
# Understanding immediate mode
`egui` is an immediate mode GUI library. It is useful to fully grok what "immediate mode" implies.
Here is an example to illustrate it:
```
# egui::__run_test_ui(|ui| {
if ui.button("click me").clicked() {
take_action()
}
# });
# fn take_action() {}
```
This code is being executed each frame at maybe 60 frames per second.
Each frame egui does these things:
* lays out the letters `click me` in order to figure out the size of the button
* decides where on screen to place the button
* check if the mouse is hovering or clicking that location
* chose button colors based on if it is being hovered or clicked
* add a [`Shape::Rect`] and [`Shape::Text`] to the list of shapes to be painted later this frame
* return a [`Response`] with the [`clicked`](`Response::clicked`) member so the user can check for interactions
There is no button being created and stored somewhere.
The only output of this call is some colored shapes, and a [`Response`].
Similarly, consider this code:
```
# egui::__run_test_ui(|ui| {
# let mut value: f32 = 0.0;
ui.add(egui::Slider::new(&mut value, 0.0..=100.0).text("My value"));
# });
```
Here egui will read `value` to display the slider, then look if the mouse is dragging the slider and if so change the `value`.
Note that `egui` does not store the slider value for you - it only displays the current value, and changes it
by how much the slider has been dragged in the previous few milliseconds.
This means it is responsibility of the egui user to store the state (`value`) so that it persists between frames.
It can be useful to read the code for the toggle switch example widget to get a better understanding
of how egui works: .
Read more about the pros and cons of immediate mode at .
# Misc
## How widgets works
```
# egui::__run_test_ui(|ui| {
if ui.button("click me").clicked() { take_action() }
# });
# fn take_action() {}
```
is short for
```
# egui::__run_test_ui(|ui| {
let button = egui::Button::new("click me");
if ui.add(button).clicked() { take_action() }
# });
# fn take_action() {}
```
which is short for
```
# use egui::Widget;
# egui::__run_test_ui(|ui| {
let button = egui::Button::new("click me");
let response = button.ui(ui);
if response.clicked() { take_action() }
# });
# fn take_action() {}
```
[`Button`] uses the builder pattern to create the data required to show it. The [`Button`] is then discarded.
[`Button`] implements `trait` [`Widget`], which looks like this:
```
# use egui::*;
pub trait Widget {
/// Allocate space, interact, paint, and return a [`Response`].
fn ui(self, ui: &mut Ui) -> Response;
}
```
## Auto-sizing panels and windows
In egui, all panels and windows auto-shrink to fit the content.
If the window or panel is also resizable, this can lead to a weird behavior
where you can drag the edge of the panel/window to make it larger, and
when you release the panel/window shrinks again.
This is an artifact of immediate mode, and here are some alternatives on how to avoid it:
1. Turn off resizing with [`Window::resizable`], [`SidePanel::resizable`], [`TopBottomPanel::resizable`].
2. Wrap your panel contents in a [`ScrollArea`], or use [`Window::vscroll`] and [`Window::hscroll`].
3. Use a justified layout:
```
# egui::__run_test_ui(|ui| {
ui.with_layout(egui::Layout::top_down_justified(egui::Align::Center), |ui| {
ui.button("I am becoming wider as needed");
});
# });
```
4. Fill in extra space with emptiness:
```
# egui::__run_test_ui(|ui| {
ui.allocate_space(ui.available_size()); // put this LAST in your panel/window code
# });
```
## Sizes
You can control the size of widgets using [`Ui::add_sized`].
```
# egui::__run_test_ui(|ui| {
# let mut my_value = 0.0_f32;
ui.add_sized([40.0, 20.0], egui::DragValue::new(&mut my_value));
# });
```
## Code snippets
```
# egui::__run_test_ui(|ui| {
# let mut some_bool = true;
// Miscellaneous tips and tricks
ui.horizontal_wrapped(|ui| {
ui.spacing_mut().item_spacing.x = 0.0; // remove spacing between widgets
// `radio_value` also works for enums, integers, and more.
ui.radio_value(&mut some_bool, false, "Off");
ui.radio_value(&mut some_bool, true, "On");
});
ui.group(|ui| {
ui.label("Within a frame");
ui.set_min_height(200.0);
});
// A `scope` creates a temporary [`Ui`] in which you can change settings:
ui.scope(|ui| {
ui.visuals_mut().override_text_color = Some(egui::Color32::RED);
ui.style_mut().override_text_style = Some(egui::TextStyle::Monospace);
ui.style_mut().wrap = Some(false);
ui.label("This text will be red, monospace, and won't wrap to a new line");
}); // the temporary settings are reverted here
# });
```
## Feature flags